/****************************************************************************
 *
 * ftmodapi.h
 *
 *   FreeType modules public interface (specification).
 *
 * Copyright (C) 1996-2019 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTMODAPI_H_
#define FTMODAPI_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

/**************************************************************************
 *
 * @section:
 *   module_management
 *
 * @title:
 *   Module Management
 *
 * @abstract:
 *   How to add, upgrade, remove, and control modules from FreeType.
 *
 * @description:
 *   The definitions below are used to manage modules within FreeType.
 *   Modules can be added, upgraded, and removed at runtime.  Additionally,
 *   some module properties can be controlled also.
 *
 *   Here is a list of possible values of the `module_name` field in the
 *   @FT_Module_Class structure.
 *
 *   ```
 *     autofitter
 *     bdf
 *     cff
 *     gxvalid
 *     otvalid
 *     pcf
 *     pfr
 *     psaux
 *     pshinter
 *     psnames
 *     raster1
 *     sfnt
 *     smooth, smooth-lcd, smooth-lcdv
 *     truetype
 *     type1
 *     type42
 *     t1cid
 *     winfonts
 *   ```
 *
 *   Note that the FreeType Cache sub-system is not a FreeType module.
 *
 * @order:
 *   FT_Module
 *   FT_Module_Constructor
 *   FT_Module_Destructor
 *   FT_Module_Requester
 *   FT_Module_Class
 *
 *   FT_Add_Module
 *   FT_Get_Module
 *   FT_Remove_Module
 *   FT_Add_Default_Modules
 *
 *   FT_Property_Set
 *   FT_Property_Get
 *   FT_Set_Default_Properties
 *
 *   FT_New_Library
 *   FT_Done_Library
 *   FT_Reference_Library
 *
 *   FT_Renderer
 *   FT_Renderer_Class
 *
 *   FT_Get_Renderer
 *   FT_Set_Renderer
 *
 *   FT_Set_Debug_Hook
 *
 */

/* module bit flags */
#define FT_MODULE_FONT_DRIVER 1 /* this module is a font driver  */
#define FT_MODULE_RENDERER 2    /* this module is a renderer     */
#define FT_MODULE_HINTER 4      /* this module is a glyph hinter */
#define FT_MODULE_STYLER 8      /* this module is a styler       */

#define FT_MODULE_DRIVER_SCALABLE 0x100      /* the driver supports      */
                                             /* scalable fonts           */
#define FT_MODULE_DRIVER_NO_OUTLINES 0x200   /* the driver does not      */
                                             /* support vector outlines  */
#define FT_MODULE_DRIVER_HAS_HINTER 0x400    /* the driver provides its  */
                                             /* own hinter               */
#define FT_MODULE_DRIVER_HINTS_LIGHTLY 0x800 /* the driver's hinter      */
                                             /* produces LIGHT hints     */

/* deprecated values */
#define ft_module_font_driver FT_MODULE_FONT_DRIVER
#define ft_module_renderer FT_MODULE_RENDERER
#define ft_module_hinter FT_MODULE_HINTER
#define ft_module_styler FT_MODULE_STYLER

#define ft_module_driver_scalable FT_MODULE_DRIVER_SCALABLE
#define ft_module_driver_no_outlines FT_MODULE_DRIVER_NO_OUTLINES
#define ft_module_driver_has_hinter FT_MODULE_DRIVER_HAS_HINTER
#define ft_module_driver_hints_lightly FT_MODULE_DRIVER_HINTS_LIGHTLY

typedef FT_Pointer FT_Module_Interface;

/**************************************************************************
 *
 * @functype:
 *   FT_Module_Constructor
 *
 * @description:
 *   A function used to initialize (not create) a new module object.
 *
 * @input:
 *   module ::
 *     The module to initialize.
 */
typedef FT_Error (*FT_Module_Constructor)(FT_Module module);

/**************************************************************************
 *
 * @functype:
 *   FT_Module_Destructor
 *
 * @description:
 *   A function used to finalize (not destroy) a given module object.
 *
 * @input:
 *   module ::
 *     The module to finalize.
 */
typedef void (*FT_Module_Destructor)(FT_Module module);

/**************************************************************************
 *
 * @functype:
 *   FT_Module_Requester
 *
 * @description:
 *   A function used to query a given module for a specific interface.
 *
 * @input:
 *   module ::
 *     The module to be searched.
 *
 *   name ::
 *     The name of the interface in the module.
 */
typedef FT_Module_Interface (*FT_Module_Requester)(FT_Module module, const char *name);

/**************************************************************************
 *
 * @struct:
 *   FT_Module_Class
 *
 * @description:
 *   The module class descriptor.  While being a public structure necessary
 *   for FreeType's module bookkeeping, most of the fields are essentially
 *   internal, not to be used directly by an application.
 *
 * @fields:
 *   module_flags ::
 *     Bit flags describing the module.
 *
 *   module_size ::
 *     The size of one module object/instance in bytes.
 *
 *   module_name ::
 *     The name of the module.
 *
 *   module_version ::
 *     The version, as a 16.16 fixed number (major.minor).
 *
 *   module_requires ::
 *     The version of FreeType this module requires, as a 16.16 fixed
 *     number (major.minor).  Starts at version 2.0, i.e., 0x20000.
 *
 *   module_interface ::
 *     A typeless pointer to a structure (which varies between different
 *     modules) that holds the module's interface functions.  This is
 *     essentially what `get_interface` returns.
 *
 *   module_init ::
 *     The initializing function.
 *
 *   module_done ::
 *     The finalizing function.
 *
 *   get_interface ::
 *     The interface requesting function.
 */
typedef struct FT_Module_Class_ {
	FT_ULong module_flags;
	FT_Long module_size;
	const FT_String *module_name;
	FT_Fixed module_version;
	FT_Fixed module_requires;

	const void *module_interface;

	FT_Module_Constructor module_init;
	FT_Module_Destructor module_done;
	FT_Module_Requester get_interface;

} FT_Module_Class;

/**************************************************************************
 *
 * @function:
 *   FT_Add_Module
 *
 * @description:
 *   Add a new module to a given library instance.
 *
 * @inout:
 *   library ::
 *     A handle to the library object.
 *
 * @input:
 *   clazz ::
 *     A pointer to class descriptor for the module.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   An error will be returned if a module already exists by that name, or
 *   if the module requires a version of FreeType that is too great.
 */
FT_EXPORT(FT_Error)
FT_Add_Module(FT_Library library, const FT_Module_Class *clazz);

/**************************************************************************
 *
 * @function:
 *   FT_Get_Module
 *
 * @description:
 *   Find a module by its name.
 *
 * @input:
 *   library ::
 *     A handle to the library object.
 *
 *   module_name ::
 *     The module's name (as an ASCII string).
 *
 * @return:
 *   A module handle.  0~if none was found.
 *
 * @note:
 *   FreeType's internal modules aren't documented very well, and you
 *   should look up the source code for details.
 */
FT_EXPORT(FT_Module)
FT_Get_Module(FT_Library library, const char *module_name);

/**************************************************************************
 *
 * @function:
 *   FT_Remove_Module
 *
 * @description:
 *   Remove a given module from a library instance.
 *
 * @inout:
 *   library ::
 *     A handle to a library object.
 *
 * @input:
 *   module ::
 *     A handle to a module object.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   The module object is destroyed by the function in case of success.
 */
FT_EXPORT(FT_Error)
FT_Remove_Module(FT_Library library, FT_Module module);

/**************************************************************************
 *
 * @function:
 *    FT_Property_Set
 *
 * @description:
 *    Set a property for a given module.
 *
 * @input:
 *    library ::
 *      A handle to the library the module is part of.
 *
 *    module_name ::
 *      The module name.
 *
 *    property_name ::
 *      The property name.  Properties are described in section
 *      @properties.
 *
 *      Note that only a few modules have properties.
 *
 *    value ::
 *      A generic pointer to a variable or structure that gives the new
 *      value of the property.  The exact definition of `value` is
 *      dependent on the property; see section @properties.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *    If `module_name` isn't a valid module name, or `property_name`
 *    doesn't specify a valid property, or if `value` doesn't represent a
 *    valid value for the given property, an error is returned.
 *
 *    The following example sets property 'bar' (a simple integer) in
 *    module 'foo' to value~1.
 *
 *    ```
 *      FT_UInt  bar;
 *
 *
 *      bar = 1;
 *      FT_Property_Set( library, "foo", "bar", &bar );
 *    ```
 *
 *    Note that the FreeType Cache sub-system doesn't recognize module
 *    property changes.  To avoid glyph lookup confusion within the cache
 *    you should call @FTC_Manager_Reset to completely flush the cache if a
 *    module property gets changed after @FTC_Manager_New has been called.
 *
 *    It is not possible to set properties of the FreeType Cache sub-system
 *    itself with FT_Property_Set; use @FTC_Property_Set instead.
 *
 * @since:
 *   2.4.11
 *
 */
FT_EXPORT(FT_Error)
FT_Property_Set(FT_Library library, const FT_String *module_name, const FT_String *property_name,
                const void *value);

/**************************************************************************
 *
 * @function:
 *    FT_Property_Get
 *
 * @description:
 *    Get a module's property value.
 *
 * @input:
 *    library ::
 *      A handle to the library the module is part of.
 *
 *    module_name ::
 *      The module name.
 *
 *    property_name ::
 *      The property name.  Properties are described in section
 *      @properties.
 *
 * @inout:
 *    value ::
 *      A generic pointer to a variable or structure that gives the value
 *      of the property.  The exact definition of `value` is dependent on
 *      the property; see section @properties.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *    If `module_name` isn't a valid module name, or `property_name`
 *    doesn't specify a valid property, or if `value` doesn't represent a
 *    valid value for the given property, an error is returned.
 *
 *    The following example gets property 'baz' (a range) in module 'foo'.
 *
 *    ```
 *      typedef  range_
 *      {
 *        FT_Int32  min;
 *        FT_Int32  max;
 *
 *      } range;
 *
 *      range  baz;
 *
 *
 *      FT_Property_Get( library, "foo", "baz", &baz );
 *    ```
 *
 *    It is not possible to retrieve properties of the FreeType Cache
 *    sub-system with FT_Property_Get; use @FTC_Property_Get instead.
 *
 * @since:
 *   2.4.11
 *
 */
FT_EXPORT(FT_Error)
FT_Property_Get(FT_Library library, const FT_String *module_name, const FT_String *property_name,
                void *value);

/**************************************************************************
 *
 * @function:
 *   FT_Set_Default_Properties
 *
 * @description:
 *   If compilation option `FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES` is
 *   set, this function reads the `FREETYPE_PROPERTIES` environment
 *   variable to control driver properties.  See section @properties for
 *   more.
 *
 *   If the compilation option is not set, this function does nothing.
 *
 *   `FREETYPE_PROPERTIES` has the following syntax form (broken here into
 *   multiple lines for better readability).
 *
 *   ```
 *     <optional whitespace>
 *     <module-name1> ':'
 *     <property-name1> '=' <property-value1>
 *     <whitespace>
 *     <module-name2> ':'
 *     <property-name2> '=' <property-value2>
 *     ...
 *   ```
 *
 *   Example:
 *
 *   ```
 *     FREETYPE_PROPERTIES=truetype:interpreter-version=35 \
 *                         cff:no-stem-darkening=1 \
 *                         autofitter:warping=1
 *   ```
 *
 * @inout:
 *   library ::
 *     A handle to a new library object.
 *
 * @since:
 *   2.8
 */
FT_EXPORT(void)
FT_Set_Default_Properties(FT_Library library);

/**************************************************************************
 *
 * @function:
 *   FT_Reference_Library
 *
 * @description:
 *   A counter gets initialized to~1 at the time an @FT_Library structure
 *   is created.  This function increments the counter.  @FT_Done_Library
 *   then only destroys a library if the counter is~1, otherwise it simply
 *   decrements the counter.
 *
 *   This function helps in managing life-cycles of structures that
 *   reference @FT_Library objects.
 *
 * @input:
 *   library ::
 *     A handle to a target library object.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @since:
 *   2.4.2
 */
FT_EXPORT(FT_Error)
FT_Reference_Library(FT_Library library);

/**************************************************************************
 *
 * @function:
 *   FT_New_Library
 *
 * @description:
 *   This function is used to create a new FreeType library instance from a
 *   given memory object.  It is thus possible to use libraries with
 *   distinct memory allocators within the same program.  Note, however,
 *   that the used @FT_Memory structure is expected to remain valid for the
 *   life of the @FT_Library object.
 *
 *   Normally, you would call this function (followed by a call to
 *   @FT_Add_Default_Modules or a series of calls to @FT_Add_Module, and a
 *   call to @FT_Set_Default_Properties) instead of @FT_Init_FreeType to
 *   initialize the FreeType library.
 *
 *   Don't use @FT_Done_FreeType but @FT_Done_Library to destroy a library
 *   instance.
 *
 * @input:
 *   memory ::
 *     A handle to the original memory object.
 *
 * @output:
 *   alibrary ::
 *     A pointer to handle of a new library object.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   See the discussion of reference counters in the description of
 *   @FT_Reference_Library.
 */
FT_EXPORT(FT_Error)
FT_New_Library(FT_Memory memory, FT_Library *alibrary);

/**************************************************************************
 *
 * @function:
 *   FT_Done_Library
 *
 * @description:
 *   Discard a given library object.  This closes all drivers and discards
 *   all resource objects.
 *
 * @input:
 *   library ::
 *     A handle to the target library.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   See the discussion of reference counters in the description of
 *   @FT_Reference_Library.
 */
FT_EXPORT(FT_Error)
FT_Done_Library(FT_Library library);

/**************************************************************************
 *
 * @functype:
 *   FT_DebugHook_Func
 *
 * @description:
 *   A drop-in replacement (or rather a wrapper) for the bytecode or
 *   charstring interpreter's main loop function.
 *
 *   Its job is essentially
 *
 *   - to activate debug mode to enforce single-stepping,
 *
 *   - to call the main loop function to interpret the next opcode, and
 *
 *   - to show the changed context to the user.
 *
 *   An example for such a main loop function is `TT_RunIns` (declared in
 *   FreeType's internal header file `src/truetype/ttinterp.h`).
 *
 *   Have a look at the source code of the `ttdebug` FreeType demo program
 *   for an example of a drop-in replacement.
 *
 * @inout:
 *   arg ::
 *     A typeless pointer, to be cast to the main loop function's data
 *     structure (which depends on the font module).  For TrueType fonts
 *     it is bytecode interpreter's execution context, `TT_ExecContext`,
 *     which is declared in FreeType's internal header file `tttypes.h`.
 */
typedef FT_Error (*FT_DebugHook_Func)(void *arg);

/**************************************************************************
 *
 * @enum:
 *   FT_DEBUG_HOOK_XXX
 *
 * @description:
 *   A list of named debug hook indices.
 *
 * @values:
 *   FT_DEBUG_HOOK_TRUETYPE::
 *     This hook index identifies the TrueType bytecode debugger.
 */
#define FT_DEBUG_HOOK_TRUETYPE 0

/**************************************************************************
 *
 * @function:
 *   FT_Set_Debug_Hook
 *
 * @description:
 *   Set a debug hook function for debugging the interpreter of a font
 *   format.
 *
 *   While this is a public API function, an application needs access to
 *   FreeType's internal header files to do something useful.
 *
 *   Have a look at the source code of the `ttdebug` FreeType demo program
 *   for an example of its usage.
 *
 * @inout:
 *   library ::
 *     A handle to the library object.
 *
 * @input:
 *   hook_index ::
 *     The index of the debug hook.  You should use defined enumeration
 *     macros like @FT_DEBUG_HOOK_TRUETYPE.
 *
 *   debug_hook ::
 *     The function used to debug the interpreter.
 *
 * @note:
 *   Currently, four debug hook slots are available, but only one (for the
 *   TrueType interpreter) is defined.
 */
FT_EXPORT(void)
FT_Set_Debug_Hook(FT_Library library, FT_UInt hook_index, FT_DebugHook_Func debug_hook);

/**************************************************************************
 *
 * @function:
 *   FT_Add_Default_Modules
 *
 * @description:
 *   Add the set of default drivers to a given library object.  This is
 *   only useful when you create a library object with @FT_New_Library
 *   (usually to plug a custom memory manager).
 *
 * @inout:
 *   library ::
 *     A handle to a new library object.
 */
FT_EXPORT(void)
FT_Add_Default_Modules(FT_Library library);

/**************************************************************************
 *
 * @section:
 *   truetype_engine
 *
 * @title:
 *   The TrueType Engine
 *
 * @abstract:
 *   TrueType bytecode support.
 *
 * @description:
 *   This section contains a function used to query the level of TrueType
 *   bytecode support compiled in this version of the library.
 *
 */

/**************************************************************************
 *
 * @enum:
 *    FT_TrueTypeEngineType
 *
 * @description:
 *    A list of values describing which kind of TrueType bytecode engine is
 *    implemented in a given FT_Library instance.  It is used by the
 *    @FT_Get_TrueType_Engine_Type function.
 *
 * @values:
 *    FT_TRUETYPE_ENGINE_TYPE_NONE ::
 *      The library doesn't implement any kind of bytecode interpreter.
 *
 *    FT_TRUETYPE_ENGINE_TYPE_UNPATENTED ::
 *      Deprecated and removed.
 *
 *    FT_TRUETYPE_ENGINE_TYPE_PATENTED ::
 *      The library implements a bytecode interpreter that covers the full
 *      instruction set of the TrueType virtual machine (this was governed
 *      by patents until May 2010, hence the name).
 *
 * @since:
 *    2.2
 *
 */
typedef enum FT_TrueTypeEngineType_ {
	FT_TRUETYPE_ENGINE_TYPE_NONE = 0,
	FT_TRUETYPE_ENGINE_TYPE_UNPATENTED,
	FT_TRUETYPE_ENGINE_TYPE_PATENTED

} FT_TrueTypeEngineType;

/**************************************************************************
 *
 * @function:
 *    FT_Get_TrueType_Engine_Type
 *
 * @description:
 *    Return an @FT_TrueTypeEngineType value to indicate which level of the
 *    TrueType virtual machine a given library instance supports.
 *
 * @input:
 *    library ::
 *      A library instance.
 *
 * @return:
 *    A value indicating which level is supported.
 *
 * @since:
 *    2.2
 *
 */
FT_EXPORT(FT_TrueTypeEngineType)
FT_Get_TrueType_Engine_Type(FT_Library library);

/* */

FT_END_HEADER

#endif /* FTMODAPI_H_ */

/* END */
